---
title: LegacyController
summary: Downloads the output of a previously tracked convert/merge request by tracking id.
status: draft
owner: Not determined from source
last_reviewed: 2026-09-17
library: PdfAPI
reference_type: embedded
---

# LegacyController

`LegacyController` retrieves the output document produced by a previously tracked convert/merge request, identified by its tracking id.

| Field | Value |
| --- | --- |
| **Controller** | `LegacyController` |
| **Base** | `System.Web.Http.ApiController` |
| **Route prefix** | `[RoutePrefix("v1/legacy")]` |
| **Source** | `PdfAPI\Controllers\v1\LegacyController.cs` |
| **Controller-level authorization** | None in code |
| **Error handling** | Per-action `try`/`catch` + `ILogService.LogException`; response then passes through `ApiResponseHandler`, whose final outer envelope is unknown** ([details](../endpoints.md#error-response-shape)) |
| **Endpoints** | 1 |

---

## GET v1/legacy/download/{trackingId}

Looks up a tracking record by id and returns the associated output document only when the tracking status is `Succeeded` and an output file path is recorded; otherwise returns an explanatory failure result.

| Field | Value |
| --- | --- |
| **HTTP verb** | `GET` |
| **Resolved route** | `v1/legacy/download/{trackingId}` |
| **Route composition** | `[RoutePrefix("v1/legacy")]` + `[Route("download/{trackingId}")]` |
| **Action** | `Download(long trackingId)` |
| **Return type** | `IHttpActionResult` (`Ok(result)`) |
| **Authorization** | [None in code](../authentication-authorization.md#authorization-enforcement) |
| **Idempotent** | Yes — repeated calls with the same `trackingId` return the same result while the underlying tracking record is unchanged* |
| **Operation** | [OP-DOWNLOAD-BY-TRACKING-ID](../operations/op-download-by-tracking-id.md) |

### Parameters

| Name | In | Type | Required | Default | Binding | Purpose |
| --- | --- | --- | --- | --- | --- | --- |
| `trackingId` | Route | `long` | Yes | — | Route segment | Identifies the tracking record to retrieve |

### Response

| Field | Value |
| --- | --- |
| **DTO** | `PdfAPI.Core.PdfResult` |
| **Media type** | `application/json` |

| Property | Type | Nullable | Purpose |
| --- | --- | --- | --- |
| `Status` | `PdfStatus` | No | Status of the tracked request |
| `Message` | `string` | Yes | Explanatory failure message when the document is not downloadable |
| `Document` | `Document` | Yes | The output document, present only when the tracked request succeeded |

### Status codes

| Status | Condition | Body |
| --- | --- | --- |
| `200 OK` | Every outcome — success, "tracking record does not exist", "output file does not exist", and any non-`Succeeded` status — all return `200` with a `PdfResult` ([BR-PDFAPI-013](../business-rules.md#br-pdfapi-013-download-requires-succeeded-status-and-output-path)) | `PdfResult` |

### Errors

| Error status | Trigger | Produced by | Body |
| --- | --- | --- | --- |
| `404 Not Found` | `{trackingId}` does not parse as `long` — the route does not match* | Framework (routing) | Framework default routing-failure body |

The `Body` column above describes only the pre-envelope detail produced by the framework's routing. Every response also passes through the globally registered `ApiResponseHandler` message handler (`SAIF.Web.API` package), which wraps or post-processes the HTTP response for the whole service. That handler's exact outer envelope shape is implemented inside the package and is not visible in this repository — see [Endpoints: Error response shape](../endpoints.md#error-response-shape).

### Business rules

- [BR-PDFAPI-013](../business-rules.md#br-pdfapi-013-download-requires-succeeded-status-and-output-path) — a tracked document is downloadable only when its status is `Succeeded` and a non-null output file path is recorded; otherwise an explanatory failure result is returned with HTTP `200`.

### Authorization

No authorization attribute or programmatic check is present. See [Authentication and authorization](../authentication-authorization.md).

### Side effects and idempotency

| Aspect | Finding |
| --- | --- |
| Records written | None — this action only reads the `PDFTracking` record (see [Data model](../data-model.md)) |
| Downstream calls | None identified |
| Files or messages produced | None — reads the previously produced output file from disk |
| Repeat-call behavior | Same result on every call while the tracking record is unchanged |

### Example

```http
GET v1/legacy/download/12345 HTTP/1.1
Host: <host>
```

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "Succeeded",
  "Document": { "FileName": "output.pdf" }
}
```

---

## Related documentation
- [API index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Endpoints](../endpoints.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Data model](../data-model.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- PdfAPI\Controllers\v1\LegacyController.cs
- PdfAPI\Services\PdfTrackingService.cs
- PdfAPI.Core\PdfResult.cs